✨ Workflow models: visual editor with live compile, YAML, diff, simulate and export - #17706

RFC phase 4 (UI) of #17620 on v5: the workflow-model Editor — a real design surface for state machines (lanes, chips, edges, drag/drop, live compile), not a form over the JSON. Follows the owner's brief: "the editor needs to be a good design tool too".

Stacked on the merged Workflows-tab (#17681) and Simulate (#17688) PRs. Includes the remainder of #17685 (P4 backend) until it merges — after rebasing on v5 that is only its changelog fragment and the route registration line.

Screenshots (hive-default copy, 22 states / 91 transitions)

Quiet default — orthogonal gutter routing, one bundled trunk per lane pair, no edge labels:

Focus mode — hovering claimed dims non-incident edges and lifts its 12 in/out edges to the front:

What

Settings → Workflows gains an Editor nav item plus Edit buttons on library rows and the detail view (owner only; hive-default offers Edit a copy). The ingest result gains Open in editor.

Layout: toolbar · templates palette · SVG canvas · inspector · bottom drawer (Problems · YAML · Diff · Simulate).

Interaction model

• Columns are lanes: add, rename (dbl-click header), reorder by dragging the header, resize with snap-to-grid, toggle terminal (shaded), delete (moves or deletes its states after confirm).
• States are chips: drag within/between lanes (updates lifecycle.column + order), dbl-click rename, Delete/Backspace, marquee multi-select, shift-click, arrow-key nudge, tabindex=0 + Enter/Delete for keyboard users.
• Transitions: drag from a chip's right-edge port to another chip; defaults on: '' and focuses the inspector field. Edges use a quiet-by-default, detail-on-focus layer shared with the library diagram (design feedback on the hive-default knot): orthogonal routing through the lane gutters with one bundled trunk per lane pair, same-lane edges stacked on the lane margin, lane-skipping edges in corridors outside the lanes (backward ones above the headers, dashed/muted), no edge labels by default (hover/select an edge for its pill label; a Labels toggle labels only the exceptional events — the most common on such as stage-change never), focus mode (hover/select a state → non-incident edges dim, incident edges come to the front in the accent colour with arrowheads; hovering an edge highlights both end chips), and fan-out collapse (>4 edges from one state into one lane → one trunk with a +N badge; hover expands, click pins). Pure router wfRouteEdges / wfOrthoPath / wfEdgeChannels / wfEdgeCommonEvent with node tests (bundling by lane pair, back edge outside, adjacent back edge in the gutter, labels hidden by default, common event tagged, fan threshold and expansion, determinism).
• Pan (wheel / space+drag / middle button), zoom (Ctrl/Cmd+wheel, ± / Fit), minimap when the model overflows, Auto-layout (topological lane order, stage-number order within lanes).
• Compile badges on chips/edges/columns with tooltips; inferred elements dashed with a one-click ✓ confirm; initial-state marker.
• Palette: common states (ids/kinds/stage numbers), common columns, and hive-default stages (fetched once). Drops assign unique slugified ids.
• Inspector: state (id + rename with reference update, label, column, stage number, owner, type, kinds, confidence, replies, citations), transition (on with declared-events datalist, guard, note), column (id, label, hint, terminal), model (name, description, source, provenance, version, derivation, initial, label prefix, scope repo).
• Live compile (300 ms debounce) → POST /api/workflows/compile; status pill compiles / N warnings / does not compile; Problems drawer click-to-select; instant client-side mirror of the compiler's refusals (wfEdLocalProblems).
• YAML drawer: two-way (model→yaml debounced while the tab is visible and unfocused; yaml→model on Apply with inline parse errors).
• Diff drawer: client-side structural diff of the working copy vs last saved (wfEdDiff, same shape as Go ModelDiff), plus stored-version diff via GET …/diff.
• Simulate drawer: compact fact table → POST /api/workflows/simulate {model, kind, facts} for the unsaved model; decided state highlighted (.wf-ed-sim-hit), others dimmed; reason + trace shown.
• History: undo/redo (Cmd/Ctrl-Z, Shift-Cmd-Z), capped snapshot stack, dirty indicator; Save posts with meta.version: '' so the store assigns the next integer, then reloads the library and reopens the saved entry; Save as…, Revert, leave-guard via hiveConfirm.
• Start screen: new blank model, duplicate hive-default, open from library, last ingest result, marketplace placeholder (phase 7).
• Export: SVG (self-contained, theme tokens resolved from the canvas), PNG (rasterised, shown inline with open-in-new-tab — no forced downloads), model JSON, model YAML.

Pure core (no DOM, node-tested)

wfEdNewModel, wfEdAddColumn, wfEdMoveColumn, wfEdRemoveColumn, wfEdAddState, wfEdMoveState, wfEdRenameState, wfEdRemoveState, wfEdAddTransition, wfEdUpdate, wfEdUniqueId, wfEdAutoLayout, wfEdLayout, wfEdDiff, wfEdLocalProblems, wfEdSvg, wfEdMinimapSvg, wfEdStatus. All deterministic and non-mutating; workflows_editor_ui_test.go runs them under node from the generated bundle.

APIs added

• POST /api/workflows/yaml — {model} → {yaml} and {yaml} → {model, error?} (JSON→YAML so field names match json tags).
• POST /api/workflows/simulate — {model, kind, facts} for an unsaved model; same response shape as the stored-model variant (reuses stageengine.Explain).
• POST /api/workflows now assigns the next integer version when meta.version is empty.
  All in dashboard/openapi.json with handler tests; read-only computations need no owner role (mirrors the GET handlers).

Guards

Plain JS/CSS in the concatenated bundle (no libraries); CSS tokens only; no toLocaleString; no forced downloads; all actions delegated via data-action except the canvas pointer listeners attached idempotently after each render. Style/import/history-cap/band-wiring ratchets, openapi route coverage, settings-search and deeplink tests pass; gen -check clean.

Verified in a browser (Chrome via CDP against a local dashboard)

New model → 3 columns → palette drops → port-drag transitions (incl. backward) → chip drag between lanes → header drag reorder → lane resize → marquee → Delete → Cmd-Z / Shift-Cmd-Z → compile pill + Problems → YAML edit → Apply (and a parse error shown inline) → Simulate highlighting the decided state → Save (v1) → edit → client diff → Save (v2) → stored-version diff → Export SVG/PNG/JSON/YAML → Library Edit reopen → hive-default Edit a copy → leave guard. Bugs found by the smoke test (YAML newlines lost through esc(), focus lost after re-render, dark export colours in light theme, crowded edge labels) are fixed in this PR.

Docs

docs/design/workflow-models.md — new "Editor (RFC phase 4, UI)" section; changelog.d/added-workflowmodel-editor.md.

Deferred

Editing events/gates/roles/rules on the canvas (available through the YAML drawer); nested regions beyond flattening; marketplace (phase 7); keyboard-only lane reorder; collaborative/locking semantics; persisted lane widths.

Refs #17620